Maintainer Review

Verdict: ⚠️ Approve with reservations

Useful feature — many documentation systems (MkDocs, Hugo) use this convention. However, this is implicit behavior that could surprise users.

Good:

• Clean separation: first pass identifies files, second pass processes them
• Folder title is overridden by document title if present (intuitive)
• No debug output, collision detection preserved (unlike upstream)
• Proper type annotations

Concerns:

1. Implicit behavior — no opt-in flag. A user with docs.md next to docs/ might not expect their file to become folder content. Consider adding an opt-in flag like --folder-content-from-file or making this controllable via .pages
2. Double directory walk — adds a full os.walk pass. For large trees this could be noticeable. Could optimize by collecting subdirs in the main loop instead
3. Edge case: what if the matching file has front matter labels? Those won't be applied to the folder page since Page.__init__ for folders doesn't pass labels through

Recommendation: Consider making this opt-in. The implicit behavior matches some static site generators but could surprise Confluence users who intentionally have both a folder and a file with the same name for different purposes.

Updated — addressed all review feedback:

1. ✅ Opt-in behavior — added --use-folder-content-file CLI flag. No implicit behavior change without it
2. ✅ Pre-scan walk skipped when flag is disabled (no perf impact when not using the feature)
3. ✅ Labels from front matter now passed through to folder page via folder_page_labels
4. ✅ New test verifying default behavior is unchanged (test_get_pages_from_directory_folder_content_disabled_by_default)